---
title: "01-Knife4j OpenAPI 3.0 完整配置指南"
created: 2025-12-02
tags:
  - 项目
aliases:
  - Knife4j OpenAPI 3.0 完整配置指南
---
# Knife4j OpenAPI 3.0 完整配置指南

## 快速开始

### 1. pom.xml 依赖配置

```xml
<!-- Knife4j OpenAPI 3.0：Swagger 增强版，API 文档生成 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>
```

### 2. 配置类（Knife4jConfig.java）

```java
package com.zwnsyw.zwwwspringbootbasetemplate.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("项目接口文档")
                        .version("1.0.0")
                        .description("RESTful API 接口说明文档")
                        .contact(new Contact()
                                .name("开发者")
                                .url("https://example.com")
                                .email("dev@example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("http://www.apache.org/licenses/LICENSE-2.0")));
    }
}
```

### 3. application.yml 配置

```yaml
server:
  port: 8080
  servlet:
    context-path: /api

knife4j:
  enable: true
```

## 访问文档

- **Knife4j 文档**：http://localhost:8080/api/doc.html
- **Swagger UI**：http://localhost:8080/api/swagger-ui.html
- **OpenAPI JSON**：http://localhost:8080/api/v3/api-docs

> **注意**：因为配置了 `context-path: /api`，所以所有地址都需要加上 `/api` 前缀

## 在 Controller 中使用注解

```java
package com.zwnsyw.zwwwspringbootbasetemplate.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "获取用户详情", description = "根据用户ID获取用户信息")
    public String getUserById(@PathVariable Long id) {
        return "User: " + id;
    }

    @PostMapping
    @Operation(summary = "创建用户", description = "创建一个新的用户")
    public String createUser(@RequestBody UserDTO user) {
        return "Created user: " + user.getName();
    }
}

class UserDTO {
    private String name;
    private String email;

    // getter/setter
}
```

## 常用注解说明

| 注解 | 说明 |
| --- | --- |
| `@Tag` | 标签，对应一组接口 |
| `@Operation` | 操作/方法描述 |
| `@Parameter` | 参数描述 |
| `@RequestBody` | 请求体描述 |
| `@ApiResponse` | 响应描述 |
| `@Schema` | 数据模型描述 |

## 环境配置

### application-dev.yml（开发环境）

```yaml
knife4j:
  enable: true
```

### application-prod.yml（生产环境）

```yaml
knife4j:
  enable: false
```

## 故障排查

### 访问 404

**问题**：访问 http://localhost:8080/doc.html 返回 404

**解决**：

1. 检查 `context-path` 配置
2. 使用正确的 URL：http://localhost:8080/api/doc.html
3. 确保应用已启动

### 无法看到接口

**问题**：文档页面显示但没有接口

**解决**：

1. 确认 Controller 类加了 `@RestController` 或 `@Controller` 注解
2. 确认方法加了 `@GetMapping` 等 HTTP 方法注解
3. 添加 `@Tag` 和 `@Operation` 注解来增强文档

### 依赖冲突

**问题**：无法识别 `io.swagger.v3` 包

**解决**：

1. 确保 pom.xml 中使用的是 `knife4j-openapi3-spring-boot-starter`（不是 openapi2）
2. 清除 Maven 缓存：`rm -rf ~/.m2/repository/com/github/xiaoymin/`
3. 重新下载：`mvn clean install -DskipTests`

## 最佳实践

1. **在生产环境禁用文档**

   ```yaml
   knife4j:
     enable: ${KNIFE4J_ENABLE:false}
   ```
2. **为所有 Controller 添加 @Tag**

   ```java
   @RestController
   @Tag(name = "功能模块", description = "功能说明")
   public class DemoController { }
   ```
3. **为所有接口添加 @Operation**

   ```java
   @GetMapping("/{id}")
   @Operation(summary = "简短描述", description = "详细描述")
   public String demo(@PathVariable Long id) { }
   ```
4. **为复杂参数添加 @Schema**

   ```java
   @Schema(description = "用户ID")
   private Long userId;
   ```

## 完整示例项目结构

```text
src/main/java/com/zwnsyw/zwwwspringbootbasetemplate/
├── config/
│   └── Knife4jConfig.java          # Knife4j 配置
├── controller/
│   ├── UserController.java         # 用户接口
│   └── ProductController.java      # 产品接口
├── dto/
│   ├── UserDTO.java
│   └── ProductDTO.java
└── ZwwwSpringBootBaseTemplateApplication.java

src/main/resources/
├── application.yml                 # 主配置
├── application-dev.yml             # 开发配置
└── application-prod.yml            # 生产配置
```

---

**项目分区导航**：⬅️ [[00-接口文档|00-接口文档]] | 01-Knife4j OpenAPI 3.0 完整配置指南 | ➡️ [[01-缓存使用最佳实践指南|01-缓存使用最佳实践指南]]